home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / tcl / tcl67.lha / tcl6.7 / doc / CrtCommand.3 < prev    next >
Text File  |  1993-01-31  |  5KB  |  125 lines
  1. '\"
  2. '\" Copyright 1989 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/tcl/man/RCS/CrtCommand.3,v 1.7 93/01/31 15:35:29 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .so man.macros
  13. .HS Tcl_CreateCommand tcl
  14. .BS
  15. .SH NAME
  16. Tcl_CreateCommand, Tcl_DeleteCommand \- define application-specific command bindings
  17. .SH SYNOPSIS
  18. .nf
  19. \fB#include <tcl.h>\fR
  20. .sp
  21. \fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
  22. .sp
  23. int
  24. \fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
  25. .SH ARGUMENTS
  26. .AS Tcl_CmdDeleteProc (*deleteProc)()
  27. .AP Tcl_Interp *interp in
  28. Interpreter in which to create new command.
  29. .AP char *cmdName in
  30. Name of command to create or delete.
  31. .AP Tcl_CmdProc *proc in
  32. Implementation of new command:  \fIproc\fR will be called whenever
  33. \fIcmdName\fR is invoked as a command.
  34. .AP ClientData clientData in
  35. Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
  36. .AP Tcl_CmdDeleteProc *deleteProc in
  37. Procedure to call before \fIcmdName\fR is deleted from the interpreter;
  38. allows for command-specific cleanup.  If NULL, then no procedure is
  39. called before the command is deleted.
  40. .BE
  41.  
  42. .SH DESCRIPTION
  43. .PP
  44. \fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
  45. it with procedure \fIproc\fR such that whenever \fIcmdName\fR is
  46. invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
  47. will call \fIproc\fR
  48. to process the command.  If there is already a command \fIcmdName\fR
  49. associated with the interpreter, it is deleted.  \fIProc\fP should
  50. have arguments and result that match the type \fBTcl_CmdProc\fR:
  51. .nf
  52. .RS
  53. typedef int Tcl_CmdProc(
  54. .RS
  55. ClientData \fIclientData\fR,
  56. Tcl_Interp *\fIinterp\fR,
  57. int \fIargc\fR,
  58. char *\fIargv\fR[]);
  59. .RE
  60. .RE
  61. .fi
  62. When \fIproc\fR is invoked the \fIclientData\fP and \fIinterp\fR
  63. parameters will be copies of the \fIclientData\fP and \fIinterp\fR
  64. arguments given to \fBTcl_CreateCommand\fR.
  65. Typically, \fIclientData\fR points to an application-specific
  66. data structure that describes what to do when the command procedure
  67. is invoked.  \fIArgc\fR and \fIargv\fR describe the arguments to
  68. the command, \fIargc\fR giving the number of arguments (including
  69. the command name) and \fIargv\fR giving the values of the arguments
  70. as strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
  71. the first \fIargc\fR values point to the argument strings, and the
  72. last value is NULL.
  73. .PP
  74. \fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
  75. \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.  See the Tcl overview man page
  76. for details on what these codes mean.  Most normal commands will only
  77. return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
  78. \fIinterp->result\fR to point to a string value;
  79. in the case of a \fBTCL_OK\fR return code this gives the result
  80. of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
  81. The \fBTcl_SetResult\fR procedure provides an easy interface for setting
  82. the return value;  for complete details on how the \fIinterp->result\fR
  83. field is managed, see the \fBTcl_Interp\fR man page.
  84. Before invoking a command procedure,
  85. \fBTcl_Eval\fR sets \fIinterp->result\fR to point to an empty string, so simple
  86. commands can return an empty result by doing nothing at all.
  87. .PP
  88. The contents of the \fIargv\fR array are copies made by the Tcl interpreter
  89. for the use of \fIproc\fR.  \fIProc\fR may alter any of the strings
  90. in \fIargv\fR.  However, the \fIargv\fR array
  91. is recycled as soon as \fIproc\fR returns, so \fIproc\fR must not set
  92. \fIinterp->result\fR to point anywhere within the \fIargv\fR values
  93. (call Tcl_SetResult
  94. with status \fBTCL_VOLATILE\fR if you want to return something from the
  95. \fIargv\fR array).
  96. .PP
  97. \fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
  98. This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
  99. or by replacing \fIcmdName\fR in another call to Tcl_CreateCommand.
  100. \fIDeleteProc\fR is invoked before the command is deleted, and gives the
  101. application an opportunity to release any structures associated
  102. with the command.  \fIDeleteProc\fR should have arguments and
  103. result that match the type \fBTcl_CmdDeleteProc\fR:
  104. .nf
  105. .RS
  106. .sp
  107. typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
  108. .sp
  109. .RE
  110. .fi
  111. The \fIclientData\fR argument will be the same as the \fIclientData\fR
  112. argument passed to \fBTcl_CreateCommand\fR.
  113. .PP
  114. \fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
  115. Once the call completes, attempts to invoke \fIcmdName\fR in
  116. \fIinterp\fR will result in errors.
  117. If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
  118. \fBTcl_DeleteCommand\fR does nothing and returns -1;  otherwise
  119. it returns 0.
  120. There are no restrictions on \fIcmdName\fR:  it may refer to
  121. a built-in command, an application-specific command, or a Tcl procedure.
  122.  
  123. .SH KEYWORDS
  124. bind, command, create, delete, interpreter
  125.